fix(#4060): add bounded jittered backoff to StartableToolSet retry path - #4062

…rt, align bounds

Addresses all blocking and should-fix findings from the aheritier review
on PR #4062:

[blocking #1 + #2] Generic classifier with HTTP-status precedence:
- Add modelerrors.RetryableHTTPStatus(err) — catches any error carrying a
  retryable HTTP status (429/408/5xx) via *StatusError or message regex,
  without string-pattern heuristics ('connection refused' stays non-retryable).
- startBackoffRetryable becomes: return err != nil && RetryableHTTPStatus(err).
  A StatusError{429} coexisting with context.DeadlineExceeded now arms the
  gate (HTTP wins), fixing the deadline-masks-rate-limit race.

[blocking #3] Bounds aligned with remediation plan:
- base = 15s, cap = 5min (was 1s/30s).
- Additive jitter [d, 1.2d] (was equal jitter [d/2, d]), guaranteeing the
  full nominal wait is always respected.

[blocking #4] Gate enforced only in the TryStart path:
- Move gate check from startLocked into new tryStartLocked (called by
  TryStart/TryStartWithTimeout only).
- Start() calls startLocked directly — mcpcatalog enable and skill
  sub-session startup are never delayed.

[should-fix #5] External recovery via StartReporter:
- tryStartLocked checks reporter.IsStarted() when started==false; a live
  reporter (e.g. after /toolset-restart) clears the gate and latches the
  wrapper without calling the underlying Start.
- New test: TestStartableToolSet_ExternalRecoveryClearsBackoffGate.

[should-fix #6] Exported constructor options for cross-package tests:
- NewStartable(ts, opts...) with StartableOption, WithStartRetryJitter,
  WithStartRetryClock.
- nowFn() clock seam; zero-value StartableToolSet still usable.

[should-fix #7] Concurrent and at-boundary tests:
- TestStartableToolSet_BackoffNoDoubleStartWithinWindow: 20 goroutines
  calling TryStart, assert underlying Start invoked exactly once.
- TestStartableToolSet_BackoffAtBoundary: fake clock, gate open at expiry.

[optional] Stale comment name in BackoffDormantForPlainErrors fixed.

Also:
- RetryableHTTPStatus test cases include plain-text regex fallback.
- ExportedSetClock removed (unused; WithStartRetryClock preferred).
- All gating tests converted from s.Start() to s.TryStart().
- Jitter-bounds assertions updated to [nominal, 1.2×nominal].

PR2 (#4065) will need rebasing and test updates after this lands.

[blocking] partial-start comment corrected; known limitation for code-mode
composites documented with reference to follow-up issue #4067

[SF1] startBackoffRetryable requires *StatusError — regex fallback excluded
to prevent false positives on port numbers and chunk counters; RetryableHTTPStatus
doc corrected to describe the actual regex-fallback behaviour

[SF2] TestStartableToolSet_BlockingStartSkipsGate: arm gate, assert blocking
Start() invokes underlying (not gated), assert TryStart() is gated

[SF3] tryStartLocked: reporter-adoption guarded by !startBackoffUntil.IsZero()
— fix is now scoped to gated state; non-gated TryStart semantics unchanged

[SF4] stale 'next turn' log messages updated in agent.go and mcp.go

[optional] ExportedSetJitter removed (dead code; WithStartRetryJitter preferred)

…rt, align bounds

Addresses all blocking and should-fix findings from the aheritier review
on PR #4062:

[blocking #1 + #2] Generic classifier with HTTP-status precedence:
- Add modelerrors.RetryableHTTPStatus(err) — catches any error carrying a
  retryable HTTP status (429/408/5xx) via *StatusError or message regex,
  without string-pattern heuristics ('connection refused' stays non-retryable).
- startBackoffRetryable becomes: return err != nil && RetryableHTTPStatus(err).
  A StatusError{429} coexisting with context.DeadlineExceeded now arms the
  gate (HTTP wins), fixing the deadline-masks-rate-limit race.

[blocking #3] Bounds aligned with remediation plan:
- base = 15s, cap = 5min (was 1s/30s).
- Additive jitter [d, 1.2d] (was equal jitter [d/2, d]), guaranteeing the
  full nominal wait is always respected.

[blocking #4] Gate enforced only in the TryStart path:
- Move gate check from startLocked into new tryStartLocked (called by
  TryStart/TryStartWithTimeout only).
- Start() calls startLocked directly — mcpcatalog enable and skill
  sub-session startup are never delayed.

[should-fix #5] External recovery via StartReporter:
- tryStartLocked checks reporter.IsStarted() when started==false; a live
  reporter (e.g. after /toolset-restart) clears the gate and latches the
  wrapper without calling the underlying Start.
- New test: TestStartableToolSet_ExternalRecoveryClearsBackoffGate.

[should-fix #6] Exported constructor options for cross-package tests:
- NewStartable(ts, opts...) with StartableOption, WithStartRetryJitter,
  WithStartRetryClock.
- nowFn() clock seam; zero-value StartableToolSet still usable.

[should-fix #7] Concurrent and at-boundary tests:
- TestStartableToolSet_BackoffNoDoubleStartWithinWindow: 20 goroutines
  calling TryStart, assert underlying Start invoked exactly once.
- TestStartableToolSet_BackoffAtBoundary: fake clock, gate open at expiry.

[optional] Stale comment name in BackoffDormantForPlainErrors fixed.

Also:
- RetryableHTTPStatus test cases include plain-text regex fallback.
- ExportedSetClock removed (unused; WithStartRetryClock preferred).
- All gating tests converted from s.Start() to s.TryStart().
- Jitter-bounds assertions updated to [nominal, 1.2×nominal].

PR2 (#4065) will need rebasing and test updates after this lands.

Regression suite for the backoff gate introduced in PR1 (#4062).

Test files:
- pkg/tools/startable_backoff_regression_test.go: 9 consumer-shaped
  regression tests using fakes modelled on real RAG/MCP/LSP error shapes —
  RAG-shaped failure+recovery, MCP/LSP compatibility (fail-fast, no backoff),
  HTTP 408 gate, concurrent starts no-multiplication, no timer/goroutine leak,
  cancellation no-window, jitter de-synchronization, already-started no-restart.
- pkg/tools/builtin/rag/rag_backoff_test.go: 2 real-toolset RAG tests using
  rag.New + countingStatusErrStrategy; proves the real toolset's StatusError
  wrapping chain is traversable by errors.As and that plain errors fail fast.

Docs:
- docs/tools/rag/index.md: authoritative 'Indexing failures, retries and
  backoff' section — retry policy (1s base, 30s cap, equal jitter), what
  triggers backoff (429, 408, 5xx) vs fail-fast (other 4xx, cancellation),
  operational impact and troubleshooting guidance.
- docs/tools/mcp/index.md: short note under Lifecycle clarifying MCP local
  startup failures fail fast; links to RAG page for full policy.
- docs/tools/lsp/index.md: matching note under Auto-Restart and Lifecycle.

No production code changes.

[blocking] partial-start comment corrected; known limitation for code-mode
composites documented with reference to follow-up issue #4067

[SF1] startBackoffRetryable requires *StatusError — regex fallback excluded
to prevent false positives on port numbers and chunk counters; RetryableHTTPStatus
doc corrected to describe the actual regex-fallback behaviour

[SF2] TestStartableToolSet_BlockingStartSkipsGate: arm gate, assert blocking
Start() invokes underlying (not gated), assert TryStart() is gated

[SF3] tryStartLocked: reporter-adoption guarded by !startBackoffUntil.IsZero()
— fix is now scoped to gated state; non-gated TryStart semantics unchanged

[SF4] stale 'next turn' log messages updated in agent.go and mcp.go

[optional] ExportedSetJitter removed (dead code; WithStartRetryJitter preferred)